docs: update declarative validation to reflect updated KEP-5073 lifecycle by aaron-prindle · Pull Request #54698 · kubernetes/website

aaron-prindle · 2026-02-26T17:09:03Z

Description

This PR updates the declarative validation documentation to reflect the new +k8s:alpha and +k8s:beta shadow lifecycle semantic detailed in recent KEP-5073 updated:

KEP-5073: Validation Lifecycle Mechanism and Updated Rollout Plan enhancements#5848
KEP-5073: Introduce DeclarativeValidationBeta and deprecate Takeover gate enhancements#5898

Summary

Removes the +k8s:declarativeValidationNative tag which has been superseded. (previously added in: docs: add stability level information to declarative validation tags #53556)
Adds documentation for the +k8s:alpha and +k8s:beta tag, which allows individual validations to run in shadow mode (collecting metrics while still allowing the existing hand-written code to be authoritative) and in authoritative mode respectively. This is used for safely migrating hand-written validation logic.
Cleans up stability level notes for isSubresource and supportsSubresource that previously referenced the deprecated native tag.

NOTE: a previous version of this PR was submitted here - #54195. This PR was created to have the changes properly target the dev-v1.36 branch and that PR was closed.

Issue

N/A

Closes: #
N/A

netlify · 2026-02-26T17:19:37Z

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`ccf4084`
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-main-staging/deploys/69a07e399aaf460008506032
😎 Deploy Preview	https://deploy-preview-54698--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2026-02-26T17:30:27Z

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`1d5c375`
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-main-staging/deploys/69cd73b68769c10008457d85
😎 Deploy Preview	https://deploy-preview-54698--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

yongruilin · 2026-03-26T20:18:34Z

content/en/docs/reference/using-api/declarative-validation.md


-Administrators can choose to explicitly enable `DeclarativeValidationTakeover=true` to make the *declarative* validation authoritative for migrated fields, typically after verifying stability in their environment (e.g., by monitoring the mismatch metric).
+Administrators can explicitly disable the `DeclarativeValidationBeta` feature gate to force `+k8s:beta` validation rules back into shadow mode if unexpected validation behavior or regressions are observed.

 ## Disabling declarative validation {#opt-out}

 As a cluster administrator, you might consider disabling declarative validation whilst it is still beta, under specific circumstances:


We're GA'ed right? I don't expect we disable the declarative validation.

I wrote this in a way that it also explained how the DeclartiveValidation feature
gate used to work in case a user is:

on older version v1.33-v1.35

using emulation version

I think its ok to write this and assume the user is using v1.36 without those constriants so I have now removed this assuming DeclarativeValidation is always on (GA'd) and removed any docs around when it is false

yongruilin · 2026-03-26T20:19:46Z

content/en/docs/reference/using-api/declarative-validation.md


 To revert to only using hand-written validation (as used before Kubernetes v1.33), disable the `DeclarativeValidation` feature gate, for example
-via command-line arguments: (`--feature-gates=DeclarativeValidation=false`). This also implicitly disables the effect of `DeclarativeValidationTakeover`.
+via command-line arguments: (`--feature-gates=DeclarativeValidation=false`). This also implicitly disables the effect of `DeclarativeValidationBeta`.


This is not an option unless in emulated version?

I wrote this in a way that it also explained how the DeclartiveValidation feature
gate used to work in case a user is:

on older version v1.33-v1.35

using emulation version

I think its ok to write this and assume the user is using v1.36 without those constriants so I have now removed this assuming DeclarativeValidation is always on (GA'd) and removed any docs around when it is false

content/en/docs/reference/using-api/declarative-validation.md

…ycle process with +k8s:alpha and +k8s:beta

yongruilin · 2026-03-26T22:17:37Z

/lgtm

k8s-ci-robot · 2026-03-26T22:17:46Z

LGTM label has been added.

Details

Git tree hash: ef332355b2dfb3a9299d470de36e570d9143208a

lmktfy · 2026-03-26T22:26:29Z

I was hoping people would review kubernetes/contributor-site#667, and then we can update it for v1.36

I don't have enough insight to review kubernetes/contributor-site#667 myself. @aaron-prindle is there anything you ought to do to move kubernetes/contributor-site#667 forward?

aaron-prindle · 2026-03-26T22:32:56Z

@lmktfy - I'm not sure I understand, these are two different changes. This PR updates the k/website tag catalog documentation with the new +k8s:alpha and +k8s:beta documentation. I am trying to get this in before the 3/31 date for docs freeze as k/website is subject to the freeze

The goal of kubernetes/contributor-site#667 is to document everything for DV. That repo (k/contributor-site) and thus the PR is not restricted by the 4/8 docs freeze so hoping to get this in first.

EDIT: docs freeze date is 4/8 not 3/31, updated

aaron-prindle · 2026-03-26T22:33:52Z

I plan on updating all of the documentation in kubernetes/contributor-site#667 but I am trying to get this merged in time for the 4/8 docs freeze date

EDIT: s/code-freeze/docs-freeze

lmktfy · 2026-03-27T07:35:55Z

We can try to get this merged ahead of k/k code freeze, but I don't really see why that'd be important. What have I missed?

lmktfy · 2026-03-27T07:36:37Z

The k/k code freeze doesn't apply to this repository, BTW.

aaron-prindle · 2026-03-27T17:48:46Z

I updated the text there, I was refererring to the 4/8 docs freeze referenced here:
https://www.kubernetes.dev/resources/release/#summary

AnshumanTripathi · 2026-04-01T17:18:51Z

Hello @aaron-prindle 👋!
I'm reaching out from the Docs team. Just checking in as we approach Docs Freeze on Wednesday 8th April 2026 (AoE) / Thursday 9th April 2026, 12:00 UTC.
This documentation appears to still be under review. To meet the Docs Freeze, this PR must have a technical review as well as lgtm and approve labels applied, without any unaddressed comments or concerns from SIG Docs.
Thank you!

aaron-prindle · 2026-04-01T18:11:20Z

@AnshumanTripathi thanks for the information there. This has a technical review from @yongruilin related to the content and now I am hoping to get a docs review /lgtm /approve the docs changes here. Can you help direct a reviewer to this PR? Thanks!

aaron-prindle · 2026-04-01T18:12:55Z

/assign @katcosgrove

katcosgrove

Small style guide issue

content/en/docs/reference/using-api/declarative-validation.md

Co-authored-by: Kat Cosgrove <kat.cosgrove@gmail.com>

yongruilin · 2026-04-01T19:56:37Z

/lgtm

k8s-ci-robot · 2026-04-01T19:56:45Z

LGTM label has been added.

Details

Git tree hash: 8ceca35ec01e0e704321f20ace34f497fe42217c

katcosgrove · 2026-04-01T20:01:17Z

/approve

k8s-ci-robot · 2026-04-01T20:01:26Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: katcosgrove

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

~~content/en/docs/OWNERS~~ [katcosgrove]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

k8s-ci-robot added this to the 1.36 milestone Feb 26, 2026

k8s-ci-robot added the language/en Issues or PRs related to English language label Feb 26, 2026

k8s-ci-robot requested review from thockin and yongruilin February 26, 2026 17:09

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Feb 26, 2026

aaron-prindle changed the title ~~docs: update declarative validation to reflect KEP-5073 lifecycle~~ docs: update declarative validation to reflect updated KEP-5073 lifecycle Feb 26, 2026

aaron-prindle force-pushed the dv-alpha-beta-update branch from ccf4084 to 8c8158d Compare February 26, 2026 17:10

aaron-prindle mentioned this pull request Feb 26, 2026

Declarative Validation Of Kubernetes Native Types With validation-gen kubernetes/enhancements#5073

Open

33 tasks

aaron-prindle force-pushed the dv-alpha-beta-update branch 2 times, most recently from 8c8158d to 70d80e8 Compare March 26, 2026 19:01

k8s-ci-robot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Mar 26, 2026

aaron-prindle force-pushed the dv-alpha-beta-update branch 2 times, most recently from c0797a5 to ed23747 Compare March 26, 2026 19:17

yongruilin reviewed Mar 26, 2026

View reviewed changes

aaron-prindle force-pushed the dv-alpha-beta-update branch 2 times, most recently from 349ceaf to d155496 Compare March 26, 2026 20:54

k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Mar 26, 2026

aaron-prindle force-pushed the dv-alpha-beta-update branch 4 times, most recently from 6feec3f to 5b5017b Compare March 26, 2026 21:08

aaron-prindle added 2 commits March 26, 2026 21:08

docs: update declarative validation to reflect updated KEP-5073 lifec…

6d617e5

…ycle process with +k8s:alpha and +k8s:beta

address-feedback: round 1

1fed020

aaron-prindle force-pushed the dv-alpha-beta-update branch from 5b5017b to 1fed020 Compare March 26, 2026 21:09

k8s-ci-robot assigned yongruilin Mar 26, 2026

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Mar 26, 2026

k8s-ci-robot assigned katcosgrove Apr 1, 2026

katcosgrove reviewed Apr 1, 2026

View reviewed changes

content/en/docs/reference/using-api/declarative-validation.md Outdated Show resolved Hide resolved

Update content/en/docs/reference/using-api/declarative-validation.md

1d5c375

Co-authored-by: Kat Cosgrove <kat.cosgrove@gmail.com>

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Apr 1, 2026

k8s-ci-robot requested review from katcosgrove and yongruilin April 1, 2026 19:36

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Apr 1, 2026

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Apr 1, 2026

k8s-ci-robot merged commit 606cced into kubernetes:dev-1.36 Apr 1, 2026
6 checks passed

Conversation

aaron-prindle commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Summary

Issue

Uh oh!

netlify bot commented Feb 26, 2026

✅ Pull request preview available for checking

Uh oh!

netlify bot commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Pull request preview available for checking

Uh oh!

yongruilin Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

aaron-prindle Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

yongruilin Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

aaron-prindle Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yongruilin commented Mar 26, 2026

Uh oh!

k8s-ci-robot commented Mar 26, 2026

Uh oh!

lmktfy commented Mar 26, 2026

Uh oh!

aaron-prindle commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aaron-prindle commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lmktfy commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lmktfy commented Mar 27, 2026

Uh oh!

aaron-prindle commented Mar 27, 2026

Uh oh!

AnshumanTripathi commented Apr 1, 2026

Uh oh!

aaron-prindle commented Apr 1, 2026

Uh oh!

aaron-prindle commented Apr 1, 2026

Uh oh!

katcosgrove left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

yongruilin commented Apr 1, 2026

Uh oh!

k8s-ci-robot commented Apr 1, 2026

Uh oh!

katcosgrove commented Apr 1, 2026

Uh oh!

k8s-ci-robot commented Apr 1, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

aaron-prindle commented Feb 26, 2026 •

edited

Loading

netlify bot commented Feb 26, 2026 •

edited

Loading

aaron-prindle commented Mar 26, 2026 •

edited

Loading

aaron-prindle commented Mar 26, 2026 •

edited

Loading

lmktfy commented Mar 27, 2026 •

edited

Loading